Add Method (Recipients Collection)
The Add
method creates and returns a new Recipient object in the Recipients collection.
Syntax
Set objRecipient
= objRecipColl.Add( [name, address, type] | [entryID]
)
Parameters
objRecipient
On successful
return, represents the new Recipient object added to the collection.
objRecipColl
Required. The
Recipients collection object.
name
Optional.
String. The display name of the recipient. When this parameter is not present,
the property of the new object is set to an empty string.
address
Optional.
String. The address of the recipient. When this parameter is not present, the
property of the new object is set to an empty string.
type
Optional.
Long. The type of recipient; the initial value for the Recipient object s Type
property. The following values are valid:
|
Recipient
type |
Value |
Description
|
|
mapiTo |
1 |
The
recipient is on the To line. |
|
mapiCc |
2 |
The
recipient is on the Cc line. |
|
mapiBcc |
3 |
The
recipient is on the Bcc line. |
When this
parameter is not present, the object uses the default value mapiTo.
entryID
Optional.
String. The identifier of a valid AddressEntry object for this recipient. No
default value is supplied for the entryID parameter. When present, the
other parameters are not used. When not present, the method uses the name,
address, and type parameters to determine the recipient.
Remarks
The name,
address, and type parameters correspond to the Recipient object s
Name, Address, and Type properties, respectively. The entryID
parameter corresponds to the child AddressEntry object s ID property.
When the entryID parameter is present, the other parameters are not
used.
When no
parameters are present, an empty Recipient object is created.
You can
access the child AddressEntry object through the Recipient object s AddressEntry
property.
Call the Resolve method after you add a
recipient.
The Index property of the new
Recipient object equals the new Count property of the Recipients collection.
The recipient
is saved in the MAPI system when you Update or Send the parent Message object.
Example
This example
adds three recipients to a message. The address for the first recipient is
resolved using the display name. The second recipient is a custom address, so
the resolve operation does not modify it. The third recipient is taken from an
existing valid AddressEntry object. The Resolve operation does not affect this
recipient.
' from the sample function "Using
Addresses"
' add 3
recipient objects to a valid message object
' 1. look
up entry in address book
Set
objOneRecip = objNewMessage.Recipients.Add( _
Name:=strName, _
Type:=mapiTo)
' error
handling...verify objOneRecip
objOneRecip.Resolve
' 2. add a
custom recipient
Set objOneRecip
= objNewMessage.Recipients.Add( _
Address:="SMTP:davidhef@microsoft.com", _
Type:=mapiTo)
If
objOneRecip Is Nothing Then
MsgBox
"Unable to add recipient using custom addressing"
Exit
Function
End If
objOneRecip.Resolve
' 3. add a
valid address entry object, such as Message.Sender
' assume
valid address entry ID, name from an existing message
Set
objOneRecip = objNewMessage.Recipients.Add( _
entryID:=strAddrEntryID, _
Name:=strName,
_
Type:=mapiTo)
If
objOneRecip Is Nothing Then
MsgBox
"Unable to add recipient using existing AddressEntry ID"
Exit
Function
End If
objNewMessage.Text = "expect 3 different recipients"
MsgBox
("count = " & objNewMessage.Recipients.Count)